<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>The stage &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Scratch blocks → Pytch functions and methods" href="non-hat-blocks.html" />
    <link rel="prev" title="Sprites" href="sprite.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="the-stage">
<h1>The stage<a class="headerlink" href="#the-stage" title="Link to this heading">¶</a></h1>
<p>Your project must have a <code class="docutils literal notranslate"><span class="pre">class</span></code> for the stage, which must be derived
from the <code class="docutils literal notranslate"><span class="pre">pytch.Stage</span></code> class.  For example,</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Stage</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Stage</span><span class="p">):</span>
    <span class="c1"># Code for your stage goes here</span>
</pre></div>
</div>
<section id="methods-and-properties-available-on-the-stage">
<h2>Methods and properties available on the Stage<a class="headerlink" href="#methods-and-properties-available-on-the-stage" title="Link to this heading">¶</a></h2>
<p>Your own version of the Stage can use the following methods, which are
provided by Pytch:</p>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">start_sound</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sound_name_or_index</span></span></em><span class="sig-paren">)</span></dt>
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">play_sound_until_done</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sound_name_or_index</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>These methods work in the same way as the ones provided by the
<code class="docutils literal notranslate"><span class="pre">Sprite</span></code> class.  See <a class="reference internal" href="sprite.html#methods-playing-sounds"><span class="std std-ref">the help in the Sprite
page</span></a> for details.  The given
<code class="docutils literal notranslate"><span class="pre">sound_name_or_index</span></code> must refer to a Sound you have defined —
see <a class="reference internal" href="sound-specs.html"><span class="doc">Defining sounds</span></a>.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.switch_backdrop">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">switch_backdrop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">backdrop_name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.switch_backdrop" title="Link to this definition">¶</a></dt>
<dd><p>Make the Stage change its backdrop to the one with the given
<code class="docutils literal notranslate"><span class="pre">backdrop_name</span></code>.  This must be the <em>label</em> of a Backdrop defined by
the class’s <code class="docutils literal notranslate"><span class="pre">Backdrops</span></code> variable — see <a class="reference internal" href="backdrop-specs.html"><span class="doc">Defining backdrops</span></a>.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">switch_backdrop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">backdrop_number</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Make the Stage change its backdrop to the one at the given position in
its list of Backdrops.  <em>Zero-based</em> indexing is used, which means
that to switch to the first backdrop, use <code class="docutils literal notranslate"><span class="pre">self.switch_backdrop(0)</span></code>;
to switch to the second backdrop, use <code class="docutils literal notranslate"><span class="pre">self.switch_backdrop(1)</span></code>; and
so on.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.next_backdrop">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">next_backdrop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.next_backdrop" title="Link to this definition">¶</a></dt>
<dd><p>Switch to the next backdrop in the Stage’s list of backdrops.  If the
Stage is already showing its last backdrop, switch to showing the
first one.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">next_backdrop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n_steps</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Switch to the backdrop <code class="docutils literal notranslate"><span class="pre">n_steps</span></code> later in the Stage’s list of
backdrops.  If this takes you beyond the end of the list, wrap back
round to the start as if in a circle.  You can use a negative number
as <code class="docutils literal notranslate"><span class="pre">n_steps</span></code> to move to an <em>earlier</em> backdrop; for example,
<code class="docutils literal notranslate"><span class="pre">self.next_backdrop(-1)</span></code> will change to the <em>previous</em> backdrop.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="self.backdrop_number">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">backdrop_number</span></span><a class="headerlink" href="#self.backdrop_number" title="Link to this definition">¶</a></dt>
<dd><p>The <em>zero-based</em> number of the currently-shown backdrop.  So if the
Stage is currently showing its first backdrop, <code class="docutils literal notranslate"><span class="pre">backdrop_number</span></code>
will be 0; if it’s currently showing its second backdrop,
<code class="docutils literal notranslate"><span class="pre">backdrop_number</span></code> will be 1; and so on.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="self.backdrop_name">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">backdrop_name</span></span><a class="headerlink" href="#self.backdrop_name" title="Link to this definition">¶</a></dt>
<dd><p>The name of the currently-shown backdrop.</p>
</dd></dl>

<section id="asking-the-user-a-question">
<h3>Asking the user a question<a class="headerlink" href="#asking-the-user-a-question" title="Link to this heading">¶</a></h3>
<p>Pytch has a method matching Scratch’s <em>ask and wait</em> block.  In
Scratch, you can find what the user typed using the <em>answer</em> reporter
block.  In Pytch, the user’s answer is <em>returned</em> to your program from
the <code class="docutils literal notranslate"><span class="pre">ask_and_wait()</span></code> method.</p>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">ask_and_wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">question</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Pop up an input box asking the <em>question</em>, and wait for the user to
type in their answer.  Your method is paused while the user is typing
their answer, and will continue once the user submits their answer.
The answer is returned, so you will usually assign it to a variable.
For example, this code assigns the user’s answer to a variable
<code class="docutils literal notranslate"><span class="pre">name</span></code> and then prints out a greeting:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">NightSky</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Stage</span><span class="p">):</span>
    <span class="c1"># [ ... Backdrops, Sounds, other methods, etc. ... ]</span>
    <span class="nd">@pytch</span><span class="o">.</span><span class="n">when_stage_clicked</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">ask_user_their_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">ask_and_wait</span><span class="p">(</span><span class="s2">&quot;What&#39;s your name?&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Hello, </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">!&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The greeting will appear in the “Output” tab of the Pytch IDE.</p>
</dd></dl>

</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Writing Pytch programs</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="sprite.html">Sprites</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">The stage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#methods-and-properties-available-on-the-stage">Methods and properties available on the Stage</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="non-hat-blocks.html">Scratch blocks → Pytch functions and methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="pytch-module-functions.html">Functions in the pytch module</a></li>
<li class="toctree-l2"><a class="reference internal" href="hat-blocks.html">Scratch hat blocks → Pytch decorators</a></li>
<li class="toctree-l2"><a class="reference internal" href="costume-specs.html">Defining costumes</a></li>
<li class="toctree-l2"><a class="reference internal" href="backdrop-specs.html">Defining backdrops</a></li>
<li class="toctree-l2"><a class="reference internal" href="sound-specs.html">Defining sounds</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-threading.html">Running many scripts at once</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../developer.html">Developer documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>